3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Groups

QuickDraw 3D provides a number of general routines for managing group objects. Unless otherwise indicated, you can use these functions with groups of any type.

Q3Group_GetType

You can use the Q3Group_GetType function to determine the type of a group.



 
TQ3ObjectType Q3Group_GetType (TQ3GroupObject group);

group: A group.

DESCRIPTION

The Q3Group_GetType function returns, as its function result, the type of the group specified by the group parameter. Q3Group_GetType returns one of these values:



 
kQ3GroupTypeDisplay

kQ3GroupTypeInfo

kQ3GroupTypeLight

If Q3Group_GetType cannot determine the type of a group or an error occurs, it returns kQ3ObjectTypeInvalid .

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_CountObjects

You can use the Q3Group_CountObjects function to determine how many objects a group contains.



 
TQ3Status Q3Group_CountObjects (

                     TQ3GroupObject group, 

                     unsigned long *nObjects);

group: A group.
nObjects: On exit, a pointer to the number of objects in the specified group.

DESCRIPTION

The Q3Group_CountObjects function returns, in the nObjects parameter, the number of objects contained in the group specified by the group parameter. If that group contains other groups, each contained group is counted only once.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_CountObjectsOfType

You can use the Q3Group_CountObjectsOfType function to determine how many objects of a particular type a group contains.



 
TQ3Status Q3Group_CountObjectsOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType, 

                     unsigned long *nObjects);

group: A group.
isType: An object type.
nObjects: On exit, a pointer to the number of objects in the specified group that have the specified type.

DESCRIPTION

The Q3Group_CountObjectsOfType function returns, in the nObjects parameter, the number of objects contained in the group specified by the group parameter that have the object type specified by the isType parameter. The object type can be either a parent class (for example, kQ3SharedType_Shape ) or a leaf class (for example, EcGeometryType_Box ).

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_AddObject

You can use the Q3Group_AddObject function to add an object to a group.



 
TQ3GroupPosition Q3Group_AddObject (

                     TQ3GroupObject group, 

                     TQ3Object object);

group: A group.
object: An object.

DESCRIPTION

The Q3Group_AddObject function inserts the object specified by the object parameter into the group specified by the group parameter. If group is a unordered group, the object is appended to the list of objects in the group. If group is an ordered group, the object is appended to the part of the list of objects in the group that are of the same type as object . Q3Group_AddObject returns the new position of the object in the group. If an error occurs as an object is inserted into the group, Q3Group_AddObject returns NULL .

ERRORS

kQ3ErrorInvalidObject kQ3ErrorOutOfMemory

Q3Group_AddObjectBefore

You can use the Q3Group_AddObjectBefore function to add an object to a group, positioning it before a certain object already in the group.



 
TQ3GroupPosition Q3Group_AddObjectBefore (

                     TQ3GroupObject group, 

                     TQ3GroupPosition position, 

                     TQ3Object object);

group: A group.
position: A group position.
object: An object.

DESCRIPTION

The Q3Group_AddObjectBefore function inserts the object specified by the object parameter into the group specified by the group parameter, before the group position specified by the position parameter. Q3Group_AddObjectBefore returns, as its function result, the new position of the object in the group. If an error occurs during the insertion of the object into the group, Q3Group_AddObjectBefore returns NULL .

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorOutOfMemory

Q3Group_AddObjectAfter

You can use the Q3Group_AddObjectAfter function to add an object to a group, positioning it after a certain object already in the group.



 
TQ3GroupPosition Q3Group_AddObjectAfter (

                     TQ3GroupObject group, 

                     TQ3GroupPosition position, 

                     TQ3Object object);

group: A group.
position: A group position.
object: An object.

DESCRIPTION

The Q3Group_AddObjectAfter function inserts the object specified by the object parameter into the group specified by the group parameter, after the group position specified by the position parameter. Q3Group_AddObjectAfter returns, as its function result, the new position of the object in the group. If an error occurs during the insertion of the object into the group, Q3Group_AddObjectAfter returns NULL .

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorOutOfMemory

Q3Group_GetPositionObject

You can use the Q3Group_GetPositionObject function to get the object located at a certain position in a group.



 
TQ3Status Q3Group_GetPositionObject (

                     TQ3GroupObject group, 

                     TQ3GroupPosition position, 

                     TQ3Object *object);

group: A group.
position: A group position.
object: On exit, a reference to a QuickDraw 3D object.

DESCRIPTION

The Q3Group_GetPositionObject function returns, in the object parameter, a reference to the object having the position specified by the position parameter in the group specified by the group parameter. The reference count of the returned object is incremented. If an error occurs when getting the object, Q3Group_GetPositionObject returns NULL .

ERRORS

kQ3ErrorInvalidObject kQ3Error_InvalidPositionForGroup kQ3Error_NULLParameter

Q3Group_SetPositionObject

You can use the Q3Group_SetPositionObject function to set the object located at a certain position in a group.



 
TQ3Status Q3Group_SetPositionObject (

                     TQ3GroupObject group, 

                     TQ3GroupPosition position, 

                     TQ3Object object);

group: A group.
position: A group position.
object: An object.

DESCRIPTION

The Q3Group_SetPositionObject function sets the object having the position specified by the position parameter in the group specified by the group parameter to the object specified by the object parameter. The object previously occupying that position is disposed of. The reference count of object is incremented.

Q3GroupPosition_SetObject returns, as its function result, either a pointer to the object installed in the specified position, or NULL if an error occurs.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidObjectForGroup kQ3ErrorInvalidObjectForPosition kQ3ErrorInvalidPositionForGroup

Q3Group_RemovePosition

You can use the Q3Group_RemovePosition function to remove an object from a group.



 
TQ3Object Q3Group_RemovePosition (

                     TQ3GroupObject group, 

                     TQ3GroupPosition position);

group: A group.
position: A group position.

DESCRIPTION

The Q3Group_RemovePosition function removes the object having the group position specified by the position parameter from the group specified by the group parameter. After you call Q3Group_RemovePosition , the position specified by the position parameter is invalid. Q3Group_RemovePosition returns, as its function result, the object removed from the group. If an error occurs when removing the object from the group, Q3Group_RemovePosition returns NULL .

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup

Q3Group_EmptyObjects

You can use the Q3Group_EmptyObjects function to remove all objects from a group.



 
TQ3Status Q3Group_EmptyObjects (TQ3GroupObject group);

group: A group.

DESCRIPTION

The Q3Group_EmptyObjects function disposes of every object contained in the group specified by the group parameter, thereby effectively emptying the contents of the group. The group itself is not disposed of.

ERRORS

kQ3ErrorInvalidObject

Q3Group_EmptyObjectsOfType

You can use the Q3Group_EmptyObjectsOfType function to remove all objects of a particular type from a group.



 
TQ3Status Q3Group_EmptyObjectsOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType);

group: A group.
isType: An object type.

DESCRIPTION

The Q3Group_EmptyObjectsOfType function disposes of every object contained in the group specified by the group parameter that has the type specified by the isType parameter.

ERRORS

kQ3ErrorInvalidObject